feat(client-generator)!: self-contained generator folders, module runtime, and eject as source - #3047

…#3045)

Each reproduced before it was fixed, each with a regression test.

An enum value of `-1` produced `VALUE_-1 = -1` — a SyntaxError that made the whole
generated Python module unusable. `enumValues` now routes every value through
`casing` (which already knew `MINUS_1`) and `uniqueIdentifiers`, so decimals,
values that fold to one name, and the empty string all stay usable. Go and PHP
built their own member names with the same folding flaw (`1.5` and `15` both
became `15`) and dedupe per enum now, with plain integers keeping their old
spelling.

PHP fataled on two operationIds that camel-case alike (`get-user`, `getUser` →
`Cannot redeclare Client::getUser()`). It now derives one deduped name per
operation, like Python and Go already did. The sample hooks in all three languages
used the raw name, so on a collision the snippet called a method that goes to a
different operation — they read the deduped map now, and `goSample` also matches
its assignment to the return shape (`err :=` for void, `stream :=` for SSE, where
`result, err :=` does not compile).

A Go array query param went through `fmt.Sprint`, putting `?tags=[a b]` on the
wire as one value. An array now repeats the key per element — proven with a real
`httptest` server: `tags=a&tags=b`.

`register()` copied seven fields and dropped `docs` and `notApplicable`, so an
ejected generator quietly did less than the built-in it replaced: `--docs` wrote
no page, ignored options stopped warning.

Two dropped-`dateType` call sites: PHP's top-level hydration returned a raw string
where its own signature declared `\DateTimeImmutable`, and Python's iterator
signatures said `str` where the method beside them said `datetime`. The defaulted
parameter was the trap, so PHP's `hydration` now requires it.

…o to the toolkit

Which response is the JSON success, whether an operation streams, and whether its
body is multipart were answered by identical private functions in python, go, and
php — and shipped three more times in the eject assets. They are one answer each
now: `jsonSuccessSchema`, `sseResponse`, and `isMultipartBody` in a new
`authoring/operation.ts`, so two generators cannot disagree about the same
operation, and a user-authored generator gets them instead of re-deriving them.

`deref` goes public with them: `authoring/schema.ts` kept it private, and php had
re-implemented it line for line.

…oolkit

`serverUrlExpression` was copied character-for-character into python, go, and php —
same regex loop, same undeclared-variable comment — differing only in how a literal
is quoted and parts are joined. The parsing is `serverUrlParts(server)` in the
toolkit now, returning literal/variable parts, and each language keeps the five
lines that are genuinely its own syntax.

…he toolkit

The scheme-key → {scheme, kind, name, in} mapping existed four times — python, go,
php, and the TypeScript descriptor — with the same OR-alternatives/AND-sets shape
and the same drop-unknown-scheme rule. It is `securityRequirements(op, model)` in
the toolkit now; each consumer keeps only its own literal syntax.

…once

The `schemaAtPointer` → is-it-an-array → take-the-raw-element block existed in
python, go, and php with the same comment about why the element must stay a `ref`.
It is `paginationItemSchema(pageSchema, itemsPointer, model)` in the toolkit now.

The envelope-header plan stays per language on purpose: its key naming carries
per-language knowledge (Go's digit-leading `N` rule, where a `_` prefix would make
the field unexported and invisible to encoding/json) that the printers own in the
next stage — promoting it here would have traded three small copies for one wrong
abstraction.

…dupe loop, no phantom parameter

The 46-word TypeScript reserved list existed twice and had to be hand-synced —
`emitters/identifier.ts` now reads `RESERVED_WORDS.typescript` (verified identical
before merging). Python's `operationIdents` re-implemented `uniqueIdentifiers`,
which the file already imported; it is a call to it now. Go keeps its own loop on
purpose: its names go through `exported`, whose digit-leading `N` rule
`identifierFor` does not know. And `paginationRuleFor` loses the `_model` parameter
nothing ever passed.

…021)

The common `Printer` keeps structure; four new printers own each language's
syntax — identifier safety, string escaping, literal rendering, comment and doc
form, the indent unit, and (for Go) the layout pass `toString()` applies. They
fill the same slots, which is the check that the abstraction is real: `typeName`,
`memberName`, `identifier`, `identifiers`, `string`, `literal`, `comment`, `doc`.

The per-language knowledge moves with them rather than being flattened: Go's
digit-leading `N` rule (a `_` prefix means unexported, so encoding/json would
silently skip the field) and its gofmt column alignment, Python's `memberName`
reporting a rename for `_field_map`, PHP's `@tag` doc form, TypeScript's
bare-or-quoted `key`. Python and Go gain a real `string()` policy — controls
escaped, non-ASCII raw, a lone surrogate spelled (`\uXXXX`) in Python and
replaced (U+FFFD) in Go, which cannot represent one — with call sites adopting it
in the next change.

python, go, and php now construct their printer and delegate naming, escaping,
and doc comments to it; their generated output is byte-identical (verified on two
fixtures each). The dogfooding guard gains the printer as a sharing tier — each
generator may import its OWN language's printer, never another's — and the eject
build rewrites the import to `@redocly/client-generator/printers/<language>`,
which is a new public subpath.

…ing policy

Both languages built string literals with `JSON.stringify` — 18 sites in python,
28 in go — relying on JSON escaping being close enough to each language's syntax.
It is not, at the edges that matter: JSON encodes an astral character (any emoji)
as a surrogate PAIR, which Go rejects outright (`\uD83C` is an invalid code point
to the compiler) and Python parses as two lone surrogates instead of the character.
A description or parameter name with an emoji broke the generated Go module and
corrupted the Python one.

Every site now goes through the printer's `string()` — controls escaped,
non-ASCII written as itself (generated files are UTF-8), a lone surrogate spelled
`\uXXXX` in Python and replaced with U+FFFD in Go, which has no spelling for one.
`pythonLiteral` delegates to the printer's `literal`, which also fixes booleans in
`Literal[...]` and enum members: JSON's lowercase `true` was never valid Python.

Output for ordinary specs is byte-identical (verified on two fixtures per
language); a spec with `"mood 🎉"` parameter and emoji enum values now
py_compiles and `go build`s.

… policy

Two escapers existed with different security policies: `codeString` escaped
U+2028/U+2029, `sanitizeCodeString` also escaped `<`/`>` to stop a `</script>`
breakout when generated output lands in an inline script. Which protection applied
depended on which one the caller imported. There is one policy now — the stricter
one, owned by `codeString` (the printers' `string()` and `sanitizeCodeString` are
the same function) — so `<` and `>` are escaped in the few places that previously
left them literal. The cafe fixture's output is unchanged; the injection e2e and
the golden snapshots pass as they are.

…rator the same verified map

… the emitters/sse helpers

… instead of a raw path and a shared HEADER

…, transformers, cli) into their generator folders

…de, DateType) to the generator toolkit types

… publish the SDK ABI as contracts/typescript

…, jsdoc, support) into the TypeScript printer module

…ination.ts)

…ifier, resolved to src by tsconfig paths and a vitest alias

…e package root

…efine the setup and pagination contracts at package level

…peScript client and the generated CLI

…l files beside their clients

…rs dissolved, ABI contracts at package level, one import guard for all ten

…d single-file path

…e-adrs

…kage -> module)